IRIX Base Documentation 2002 November

home *** CD-ROM | disk | FTP | other *** search

/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / libdl / dlopen.z / dlopen

Wrap

Text File | 2002-10-03 | 22.9 KB | 407 lines

DLOPEN(3C) Last changed: 2-23-99 NNAAMMEE ddllooppeenn, ssggiiddllooppeenn__vveerrssiioonn - Opens a Dynamic Shared Object (DSO) SSYYNNOOPPSSIISS cccc [_o_p_t_i_o_n_s ...] _f_i_l_e ...... --llcc [_l_i_b_r_a_r_y ......] ##iinncclluuddee <<ddllffccnn..hh>> (Required for both ddllooppeenn and for ssggiiddllooppeenn__vveerrssiioonn) ##iinncclluuddee <<eellff..hh>> (Required for ssggiiddllooppeenn__vveerrssiioonn only) vvooiidd **ddllooppeenn((ccoonnsstt cchhaarr **_p_a_t_h_n_a_m_e,, iinntt _m_o_d_e_1 [ || _m_o_d_e_2 ]));; vvooiidd **ssggiiddllooppeenn__vveerrssiioonn((ccoonnsstt cchhaarr **_p_a_t_h_n_a_m_e,, iinntt _m_o_d_e_1 [ || _m_o_d_e_2 ],, ccoonnsstt cchhaarr **_v_e_r_s_i_o_n,, iinntt _f_l_a_g_s));; IIMMPPLLEEMMEENNTTAATTIIOONN IRIX systems DDEESSCCRRIIPPTTIIOONN ddllooppeenn and ssggiiddllooppeenn__vveerrssiioonn belong to a family of routines that provides direct access to the dynamic linking facilities. These routines are available in a library that is loaded if the --llcc option is used with the CCCC(1), cccc(1), ff9900(1), ff7777(1), or lldd(1) command lines. ddllooppeenn makes a shared object available to a running process. It returns a handle to the process, which the process can use on subsequent calls to ddllssyymm(3C) and ddllcclloossee(3C). This handle should not be interpreted in any way by the process. ssggiiddllooppeenn__vveerrssiioonn dynamically loads DSOs in a way similar to ddllooppeenn. However, unlike ddllooppeenn, the interface version of the DSO is specified (on the _v_e_r_s_i_o_n and _f_l_a_g_s arguments) so that the dynamic linker tries to map in the DSO with the matching interface version. Aside from the restriction to a particular DSO _v_e_r_s_i_o_n, the effect of ssggiiddllooppeenn__vveerrssiioonn is identical to that of ddllooppeenn. These routines accept the following arguments: _p_a_t_h_n_a_m_e Specifies the path name of the object to be opened. It can be an absolute path or it can be relative to the current directory. If the value of _p_a_t_h_n_a_m_e is 0, ddllooppeenn makes the symbols contained in the original aa..oouutt file, and all of the objects that were loaded at program startup with the aa..oouutt file, available through ddllssyymm(3C). _m_o_d_e_1 Specifies when relocations can occur. This is the primary mode. When a DSO is brought into the address space of a process, it might contain references to symbols whose addresses are not known until the object is loaded. These references must be relocated before the symbols can be accessed. _m_o_d_e_1 governs when these relocations occur. Specify either RRTTLLDD__LLAAZZYY or RRTTLLDD__NNOOWW for _m_o_d_e_1, as follows: _m_o_d_e_1 AArrgguummeenntt RRTTLLDD__LLAAZZYY Specifies that only references to data symbols are relocated when the object is loaded. References to functions are not relocated until a given function is invoked for the first time. This _m_o_d_e should result in the best performance because a process cannot reference all of the functions in any given shared object. RRTTLLDD__NNOOWW Specifies that all necessary relocations are performed when the object is first loaded. This might result in some wasted effort if relocations are performed for functions that are never referenced, but it is useful for programs that need to know as soon as an object is loaded that all symbols referenced during execution are available. _m_o_d_e_2 Refines the _m_o_d_e_1 specification. This is the secondary mode. You must include a _m_o_d_e_1 specification in order to specify a _m_o_d_e_2. The _m_o_d_e_2 argument must be preceded by an OR bar (||). Specify either RRTTLLDD__GGLLOOBBAALL or RRTTLLDD__LLOOCCAALL for _m_o_d_e_2. If _m_o_d_e_2 is not specified, RRTTLLDD__LLOOCCAALL is assumed. The _m_o_d_e_2 specifications are as follows: _m_o_d_e_2 AArrgguummeenntt RRTTLLDD__GGLLOOBBAALL Modifies the treatment of the symbols in the DSO being opened to be identical to those of ssggiiddllaadddd(3C). With RRTTLLDD__GGLLOOBBAALL, the returned handle is less necessary than without RRTTLLDD__GGLLOOBBAALL because rrlldd(5) directly resolves references to symbols when RRTTLLDD__GGLLOOBBAALL is specified and ddllssyymm(3C) is not needed. RRTTLLDD__LLOOCCAALL Specifies that symbols in the DSO are not made globally visible. Default. For more information on the effects of RRTTLLDD__GGLLOOBBAALL and RRTTLLDD__LLOOCCAALL, see the NNAAMMEESSPPAACCEE IISSSSUUEESS and SSYYMMBBOOLL VVIISSIIBBIILLIITTYY sections of this man page. _v_e_r_s_i_o_n Specify a string that identifies the software version number. For more information on _v_e_r_s_i_o_n strings, see the lldd(1) man page and the _H_o_w _a_r_e _m_u_l_t_i_p_l_e _v_e_r_s_i_o_n_s _o_f _D_S_O_s _s_u_p_p_o_r_t_e_d? question on the ddssoo(5) man page. The _v_e_r_s_i_o_n should be a single version, such as ssggii22..00. Multiple versions are not accepted, meaning ssggii22..00::ssggii22..11 is incorrect as a value of the version string. While the effect of passing multiple versions in the string is undefined, the effect has been to treat ssggii22..00::ssggii22..11 as if it were ssggii22..00, unless LLLL__RREEQQUUIIRREE__MMIINNOORR was set in the _f_l_a_g_s argument. If multiple versions are in the _v_e_r_s_i_o_n argument, and LLLL__RREEQQUUIIRREE__MMIINNOORR is in the _f_l_a_g_s argument, version matching fails. _f_l_a_g_s Specify either LLLL__NNOONNEE or LLLL__RREEQQUUIIRREE__MMIINNOORR. Specifying LLLL__NNOONNEE means that the exact version must be present, but the minor version number is ignored in comparisons. Specifying LLLL__RREEQQUUIIRREE__MMIINNOORR means that only that precise major and minor version are accepted. NNAAMMEESSPPAACCEE IISSSSUUEESS This section does not address symbol resolution from ddllssyymm(3C). For details on its symbol resolution rules, see the ddllssyymm(3C) man page. Name resolution can become surprisingly complicated and nonintuitive in the presence of programs or DSOs that use ddllooppeenn, ssggiiddllaadddd(3C), ssggiiddllooppeenn__vveerrssiioonn, or LLLL__DDEELLAAYY__LLOOAADD (the --ddeellaayy__llooaadd option to the lldd(1) command). If there is only one definition of a symbol across all loaded DSOs, that definition is used if it is visible. For more information on visibility, see the SSYYMMBBOOLL VVIISSIIBBIILLIITTYY section of this man page. Name searches are done in the order of a single list, called the _r_l_d-_l_i_s_t. The first rld-list entry is the program itself. Following that is the list of DSOs currently in the runtime of the program. At program startup, a breadth-first list of DSOs in the program (and, recursively their library lists) is formed in the rld-list. No DSO is added to the rld-list twice. If there is a later occurrence of a DSO, the earlier occurrence is used. For an exception, see the NNOOTTEESS section of this man page. For any DSO library list entry marked LLLL__DDEELLAAYY__LLOOAADD, the referenced DSO is not loaded at program startup. An exception to the name search rule is made if a DSO is marked as DDTT__SSYYMMBBOOLLIICC. In this case, all name searches from within that DSO begin at the DSO itself and continue with the standard rld-list search. For more information on this, see the --BBssyymmbboolliicc option to the lldd(1) command. When, as a result of a call to a function in a DSO that has been loaded by using LLLL__DDEELLAAYY__LLOOAADD, that DSO is loaded and the new DSO is added at the end of the rld-list. If it has any entries in its library list that are not marked LLLL__DDEELLAAYY__LLOOAADD, the DSOs that are not delay-loaded are added recursively (breadth-first). Depending on the order of calls to delay-loaded DSOs, the order of DSOs on the rld-list might be different from one run of a program to the next. The order of DSOs in the rld-list might not match the order in any given library list because if a DSO is already in the rld-list, it is not added a second time to the rld-list. As a result of the rule that the search order is in rld-list order, the symbol that is found can be surprising. Consider a symbol AA found in DSOs BB and CC. Further, DSO BB is before DSO CC in EE's library list while DSO BB is after DSO CC in FF's library list. Neither DSO BB nor DSO CC are otherwise referenced. If DSO EE is opened by using ddllooppeenn with a _m_o_d_e of RRTTLLDD__GGLLOOBBAALL and it is opened before DSO FF, the AA from DSO BB is found by ddllssyymm(3C) from either handle. Similarly, if DSO FF is opened by using ddllooppeenn with a _m_o_d_e of RRTTLLDD__GGLLOOBBAALL and it is opened before DSO EE, the AA from DSO CC is found by ddllssyymm(3C) from either handle. However, if only one of the DSOs EE or FF is opened by using ddllooppeenn with a _m_o_d_e of RRTTLLDD__GGLLOOBBAALL, one gets DSO BB's AA from DSO EE's handle and one gets DSO CC's AA from DSO FF's handle. Note that ddllcclloossee(3C) does not cause any reordering of the rld-list. When the last handle (direct or indirect) on a DSO is closed with ddllcclloossee(3C), the DSO is removed from the rld-list. Before the final ddllcclloossee(3C), the DSO remains where it was on the rld-list. SSYYMMBBOOLL VVIISSIIBBIILLIITTYY DSOs loaded by a single invocation of ddllooppeenn can import symbols from one another or from any DSO that is globally visible, but DSOs loaded by one ddllooppeenn invocation cannot directly reference symbols from DSOs loaded by a different ddllooppeenn invocation. You can reference those symbols indirectly, however, by using ddllssyymm(3C). Globally visible DSOs are those added at program startup or via delay-load from a globally-visible object. In addition, any DSO added by ssggiiddllaadddd(3C), by ddllooppeenn with a _m_o_d_e of RRTTLLDD__GGLLOOBBAALL, or by ssggiiddllooppeenn__vveerrssiioonn with a _m_o_d_e of RRTTLLDD__GGLLOOBBAALL is globally visible. DSOs opened with RRTTLLDD__LLOOCCAALL are not globally visible. Even in a globally visible DSO, a symbol is invisible to any access from outside the DSO if the symbol is marked SSTTOO__HHIIDDDDEENN; for an example of this see the lldd(1) man page's descriptions for the --hhiiddddeenn__ssyymmbbooll or --hhiiddeess__ffiillee options. From within a DSO, all symbols in that DSO are visible. From within a DSO, all globally visible symbols are visible. Consider the following set of DSOs: ld -shared -all F.a -o F.so ld -shared -all G.a -o G.so ld -shared -all E.a F.so G.so -o E.so ld -shared -all H.a F.so -o H.so Consider the following conditions: * A program contains ddllooppeenn((""EE..ssoo"",,RRTTLLDD__LLAAZZYY)) and ddllooppeenn((""HH..ssoo"",,RRTTLLDD__LLAAZZYY)). * The program uses ddllssyymm to find functions through the two handles and calls these two functions. * Each of these calls a function that calls ffff(()) in FF..ssoo. * ffff(()) calls ffgg(()), which is defined only in GG..ssoo. Logically, you could assume that the call through the function accessed via EE..ssoo would resolve to ffgg(()) in GG..ssoo and that the call through the function accessed via HH..ssoo would result in an undefined function. However, rrlldd(5) does not attempt to determine (by walking the run-time stack or other means) the exact call stack to ffff(()). The call stack is not really enough; rrlldd(5) needs to know the handle used to derive the calls. The result of the call to ffgg(()) is undefined. What happens is that ffgg(()) in GG..ssoo is called, since such would be legal if the call path were through the handle in EE..ssoo. It is unwise to depend on such behavior. SSEEAARRCCHHIINNGG FFOORR DDSSOOss If other DSOs were link edited with _p_a_t_h_n_a_m_e when _p_a_t_h_n_a_m_e was built, those objects are automatically loaded by ddllooppeenn. This is subject to the LLLL__DDEELLAAYY__LLOOAADD library list flag. The directory search path that is used to find both _p_a_t_h_n_a_m_e and the other needed objects is the same as that used by rrlldd(5). In particular, _p_a_t_h_n_a_m_e is searched for in the following locations: * The directory specified by _p_a_t_h_n_a_m_e if it is not a simple file name (that is, it contains a slash (//) character). If it is not a simple file, _p_a_t_h_n_a_m_e is the only location searched; the other locations are ignored. * Any path specified via the --rrppaatthh argument to lldd(1) when the executable file was statically linked. * Any directory specified by the LLDD__LLIIBBRRAARRYY__PPAATTHH environment variable. This environment variable should contain a colon-separated list of directories, in the same format as the PPAATTHH variable (see sshh(1)). 64-bit programs examine the LLDD__LLIIBBRRAARRYY6644__PPAATTHH variable, and if it is not set, they examine the LLDD__LLIIBBRRAARRYY__PPAATTHH variable. New 32-bit ABI programs examine the LLDD__LLIIBBRRAARRYYNN3322__PPAATTHH variable and if it is not set, they examine the LLDD__LLIIBBRRAARRYY__PPAATTHH variable. All of these variables are ignored if the process is running sseettuuiidd or sseettggiidd (see eexxeecc(2)). * The default search paths. The paths differ depending on ABI. For information on the specific search paths, see the rrlldd(5) man page. If the process is running sseettuuiidd or sseettggiidd, the __RRLLDD__RROOOOTT, __RRLLDDNN3322__RROOOOTT, or __RRLLDD6644__RROOOOTT variable (the exact variable name depends on the ABI being used) is ignored (see rrlldd(5)). NNOOTTEESS You can open objects whose names resolve to the same absolute or relative path name any number of times by using ddllooppeenn. However, the referenced object is loaded only once into the address space of the current process. The same object referenced by two different path names, however, can be loaded multiple times. For example, given the object //uussrr//hhoommee//mmee//mmyylliibbss//mmyylliibb..ssoo, and assuming the current working directory is //uussrr//hhoommee//mmee//wwoorrkkddiirr, the following code results in mmyylliibbss..ssoo being loaded twice for the current process: ... void *handle1; void *handle2; handle1 = dlopen("../mylibs/mylib.so", RTLD_LAZY); handle2 = dlopen("/usr/home/me/mylibs/mylib.so", RTLD_LAZY); ... On the other hand, given the same object and current working directory, if LLDD__LLIIBBRRAARRYY__PPAATTHH==//uussrr//hhoommee//mmee//mmyylliibbss, the following code results in mmyylliibbss..ssoo being loaded only once: ... void *handle1; void *handle2; handle1 = dlopen("mylib.so", RTLD_LAZY); handle2 = dlopen("/usr/home/me/mylibs/mylib.so", RTLD_LAZY); ... Users who use ddllssyymm((00,,mmooddee)) to gain access to the symbol table of the aa..oouutt file itself should be aware that some symbols defined in the aa..oouutt file might not be available to the dynamic linker. The symbol table created by lldd(1) for use by the dynamic linker might contain only a subset of the symbols defined in the aa..oouutt file, specifically those referenced by the shared objects with which the aa..oouutt file is linked. Because there is no defined mechanism for dynamic loading in nonshared programs, a program built as nonshared (for example, by using cccc --nnoonn__sshhaarreedd) cannot usefully call ddllooppeenn, ddllssyymm(3C), ddlleerrrroorr(3C), ssggiiddllooppeenn__vveerrssiioonn, ssggiiddllaadddd(3C), or ddllcclloossee(3C). The dynamic loading routines are not included in the nonshared lliibbcc..aa file, so attempting to use them might result in a failure at link time. Any program built as nonshared that wishes to retain code that calls the dynamic loading routines must implement its own versions of ddllooppeenn, ddllssyymm(3C), and so on, and simply return appropriate error values to avoid the link-time errors. Note that building programs as nonshared is not generally recommended because not all libraries are available as nonshared. Using ddllcclloossee(3C) on a DSO, with __RRLLDD__AARRGGSS set to --ss in the environment, can cause surprising side effects. This is because ddllcclloossee(3C) forces many symbol GOT entries to be reset for re-lazy-evaluation. A result of this is that function pointers previously saved by the application or some library might hold values that could be obsolete or no longer correct. This is a problem for any ddllcclloossee(3C) process, but it is more serious when ddllcclloossee(3C) is used to close a handle on a globally-visible DSO. Symbol lookups proceed in order on a linear list, and a DSO is not opened twice with the same version number (unless different ddllooppeenn paths make the DSO name appear different to rrlldd(5)). When multiple ssggiiddllaadddd(3C) processes are executed and ddllcclloossee(3C) is used to close an earlier DSO, this can change the symbol to which a call is resolved. For more information, see the NNAAMMEESSPPAACCEE IISSSSUUEESS section. EEXXAAMMPPLLEESS The following specifies the RRTTLLDD__LLAAZZYY and RRTTLLDD__LLOOCCAALL modes: dlopen("X.so",RTLD_LAZY|RTLD_LOCAL); The following example program uses ddllooppeenn and was compiled with the --3322 compiler command line option: dltry.c: ------- /* Error handling code not shown. */ #include <dlfcn.h> typedef int (*xamplefuncptr)(int); int main() { void *handle; int i; xamplefuncptr fptr; handle = dlopen("greetings.so", RTLD_LAZY|RTLD_LOCAL); fptr = (xamplefuncptr)dlsym(handle, "greetings"); i = (*fptr)(3); return 0; } greetings.c: ----------- #include <stdio.h> int greetings(int num_greetings) { int i; for (i=0; i < num_greetings; i++) printf ("hello world\n"); return 1; } % cc -32 -c dltry.c greetings.c % ld -32 -shared greetings.o -soname greetings.so -o greetings.so % cc -32 dltry.o % LD_LIBRARY_PATH=. % export LD_LIBRARY_PATH % a.out hello world hello world hello world RREETTUURRNN VVAALLUUEESS If _p_a_t_h_n_a_m_e cannot be found, cannot be opened for reading, is not a DSO, or if an error occurs during the process of loading _p_a_t_h_n_a_m_e or relocating its symbolic references, ddllooppeenn returns NNUULLLL. More detailed diagnostic information is available through ddlleerrrroorr(3C). SSEEEE AALLSSOO CCCC(1), cccc(1), ff7777(1), ff9900(1), lldd(1), sshh(1) eexxeecc(2) ddllcclloossee(3C), ddlleerrrroorr(3C), ddllssyymm(3C), ssggiiddllaadddd(3C), ddssoo(5), rrlldd(5) This man page is available only online.